package com.wsg.dep.buf;

/**
 * RingQueue环形队列接口定义
 * @param <E> 队列中存储元素的类型
 */
public interface RingQueue<E> {

    /**
     * 获取当前环形缓冲区写入的最新位置
     * @return
     */
    long getCursor();

    /**
     * 向环形队列发布事件
     * @param element 要添加的元素
     * @return 添加成功返回true，队列满时返回false
     */
    boolean push(E element);

    /**
     * 从RingQueue中取出开始位置的第一个可用元素
     * @return 存在则返回，队列为空返回空
     */
    E poll();

    /**
     * 从RingQueue中取出指定位置的元素
     * @param index 指定位置
     * @return 存在则返回，不存在则返回空
     */
    E poll(long index);

    // 状态查询功能
    /**
     * 获取RingQueue的容量
     * @return RingQueue的最大存储数量
     */
    int capacity();

    /**
     * 获取RingQueue中当前元素的数量
     * @return 当前存储的元素个数
     */
    int size();

    /**
     * 判断RingQueue是否已满
     * @return 若已满返回true，否则返回false
     */
    boolean isFull();


    // 特殊操作功能
    /**
     * 清空RingQueue中的所有元素
     */
    void clear();

}
